Agent Configuration

This page explains every property of AgentConfig—the heart of the Mobile SDK initialisation process. Use it as a reference when wiring the SDK into your React Native (or Node) application.

Quick start – If you just need a working snippet jump to Full example. The rest of the page dives into the why behind every flag.

packages/sdk/src/agent.types.ts

export interface AgentConfig {
  encryptionKey: string;
  home: HomeSetttings;
  ialDefinitions?: CredentialIALDefinition[];
  identityDefinition?: IdentityDefinition;
  callbackHandlers?: CallbackHandlers;
  eventHandlers?: EventHandlers;
  autoProcessIncomingMessages?: boolean;
  webSocketSettings?: WebSocketSettings;
  dbName?: string;
  userInfo?: UserInfo;
  activityCallbackHandlers?: ActivityCallbackHandlers;
  appSecurityEnabled?: boolean;
  appCheckToken?: string;
}

---

1. Core security & integrity settings

Field	Required	Description
encryptionKey	✔︎	AES‑256 key used to transparently encrypt / decrypt the local SQLite wallet. Store it in the device Keychain / Keystore and never hard‑code it.
appSecurityEnabled	✖︎	Toggles runtime tamper‑proofing. When true (default in production builds) the SDK performs: emulator detection, jailbreak / root checks, debug & charging checks, plus SSL‑pinning registration (see below). Set to false only in dev/test builds to avoid blocking your debugger.
appCheckToken	✖︎	A Firebase App Check attestation token proving this binary comes from you. The token is forwarded with every request, letting backend services discard traffic from repackaged apps or emulators.
home.sslPinningSettings	✖︎	Enables public‑key SSL pinning for the agency domain. Supply one or more SHA‑256 SPKI hashes.
home.isAllowUntrustConnections	✖︎	Development escape hatch. When true the TLS chain is not validated—handy for local endpoints with self‑signed certs. Never enable in production.

🔒 SSL pinning

The SDK pin the server’s public key rather than the whole certificate, surviving normal renewals.

const sslSettings: SslPinningSettings = {
  publicKeyHashes: [
    "SHA-256", // SHA‑256 value of the domain
  ],
};

• Why? Mitigates man‑in‑the‑middle attacks even if a rogue CA issues a certificate for your domain.
• What happens on failure? onSslPinningFailure fires; you can sign the user out or show an error screen.

🔐 Runtime app‑security checks

When appSecurityEnabled is true the ReactNativeAppSecurityService performs:

• Emulator / simulator detection
• Root / jailbreak detection
• Debug/ADB detection
• Power state check – blocks if the device is charging (optional but prevents hardware debug boxes)

If any check fails, isAppSecure() returns false and the SDK refuses to initialise. Keep it enabled in production, disable in debug builds:

appSecurityEnabled: __DEV__ ? false : true,

---

2. Home agency settings (home)

export type HomeSetttings = {
  did?: string;
  linkedDomain?: string;   // e.g. "https://w1.dev-one37.id"
  publicKeyHex: string;    // 32‑byte Ed25519 public key in hex
  sslPinningSettings?: SslPinningSettings;
  isAllowUntrustConnections?: boolean;
};

Field	Required	Description
publicKeyHex	✔︎	Long‑term Ed25519 key used by the agency to sign DIDComm envelopes. Obtain it from the backend team.
did	✖︎	Full DID of the agency (e.g. did:web:w1.dev-one37.id). If omitted the SDK resolves it from linkedDomain.
linkedDomain	✖︎	HTTPS origin of the agency REST & WebSocket endpoints. Required for SSL pinning and deep‑link parsing.
sslPinningSettings	✖︎	See SSL pinning.
isAllowUntrustConnections	✖︎	Skip TLS verification (development only).

---

3. Identity & assurance settings

a) ialDefinitions (Identity Assurance Level mapping)

Define how particular credentials contribute to the user’s overall IAL. The SDK picks the highest IAL satisfied by the wallet.

const ialDefinitions: CredentialIALDefinition[] = [
  {
    issuerDid: "did:web:137.dev-one37.id",
    schemaName: "com.one37id.identitycard",
    mapping: [
      { condition: "equals", trustlevel: 2, ial: IALLevel.IAL2 },
      { condition: "greaterEquals", trustlevel: 3, ial: IALLevel.IAL3 },
    ],
  },
];

b) identityDefinition

Constrains which credential(s) are allowed to populate the user’s primary identity card and whether the wallet can hold more than one identity at a time.

---

4. Communications

Field	Description	Default
webSocketSettings.idleTimeoutSeconds	Connection is closed after this many seconds of no traffic.	900 (15 min)
webSocketSettings.scanIntervalSeconds	How often the idle timer is evaluated.	5 s
webSocketSettings.transports	Fallback sequence for Socket.IO.	['polling','websocket','webtransport']
autoProcessIncomingMessages	When true the SDK automatically decrypts & stores DIDComm messages; set false if you want full manual control.	true

---

5. Storage & persistence

Field	Description
dbName	Custom SQLite filename. Useful if the app hosts multiple wallets (e.g. per profile).
encryptionKey	Already covered—used to encrypt dbName.sqlite.

---

6. User metadata (userInfo)

Captures non‑PII values that help the agency personalise the UX or issue device‑bound credentials.

const userInfo: UserInfo = {
  name: "Alice Example",
  deviceVendor: DeviceVendor.IOS,
};

---

7. Handlers

The following handler collections let your host app plug into SDK lifecycle events. They are documented separately:

• Callback Handlers
• Activity Callback Handlers

Include them in AgentConfig to enable custom UI flows, analytics, etc.

---

Full example

App.tsx

import DeviceInfo from "react-native-device-info";
import { AgentConfig, DeviceVendor, IALLevel } from "@one37/mobile-sdk";

export const agentConfig: AgentConfig = {
  encryptionKey: SecureStore.get("walletKey"),
  home: {
    linkedDomain: "https://one37.id",
    publicKeyHex: "ff9cf8a136cb704934c4b9f9292f56ff2bcb2b4174740b9v116cb6452e3c11d5",
    sslPinningSettings: {
      publicKeyHashes: [
        "PeOHl6QOoKOjOL5q1KZ7cUfmm2HbBqurqWh9t62MI=",
      ],
    },
  },
  webSocketSettings: {
    idleTimeoutSeconds: 15 * 60,
    scanIntervalSeconds: 5,
  },
  appCheckToken: store.getState().onboarding.appCheckToken,
  appSecurityEnabled: !__DEV__,
  userInfo: {
    name: `${profile.firstName} ${profile.lastName}`,
    deviceVendor: DeviceInfo.getSystemName() === "iOS" ? DeviceVendor.IOS : DeviceVendor.Android,
  },
  ialDefinitions: [/* …see above… */],
  identityDefinition: { /* … */ },
  callbackHandlers,
  eventHandlers,
  activityCallbackHandlers,
};

---

Troubleshooting checklist

1. isAppSecure() returns false on rooted Android → Disable appSecurityEnabled only for QA devices; production users should be blocked.
2. WebSocket closes immediately → Increase idleTimeoutSeconds or inspect reverse‑proxy timeout settings.